home *** CD-ROM | disk | FTP | other *** search
/ ETO Development Tools 2 / ETO Development Tools 2.iso / Essentials / Developer Essentials Nov 90 / Apple II / Apple.II.partition / Utilities / APW.ORCA.Cmds / Gregs.APW.Utils / Libraries / CInclude / ToolLib.h
Encoding:
C/C++ Source or Header  |  1990-06-24  |  7.6 KB  |  205 lines  |  [TEXT/pdos]
  1. /*
  2.  *
  3.  *  ToolLib.h - Interface file for functions contained in
  4.  *      ToolLib library.  These functions can be used by
  5.  *      programs that are to be operated as tools under the
  6.  *      APW shell on the Apple IIgs.
  7.  *
  8.  *  Copyright Apple Computer, Inc. 1989
  9.  *  All rights reserved
  10.  *
  11.  *  Author: Greg Branche
  12.  *
  13.  */
  14.  
  15. #ifndef __ToolLib__
  16. #define __ToolLib__
  17.  
  18. /************************************************************
  19.  
  20.     <<< CursorCtl - Cursor Control Routines >>>
  21.  
  22.     This file contains:
  23.     
  24.     InitCursorCtl(delaycount) - Init CursorCtl to set the spin delay
  25.     RotateCursor(counter) - Sequence through cursor frames for counter mod
  26.                             delay
  27.     SpinCursor(increment) - Sequence mod delay incrementing internal counter
  28.     Hide_Cursor() - Hide the current cursor
  29.     Show_Cursor() - Show the cursor
  30.  
  31. ************************************************************/
  32.  
  33. extern pascal void InitCursorCtl(/* delaycount */);/*
  34. unsigned long   delaycount;
  35.  
  36.     Initialize the CursorCtl unit.  This should be called once prior to calling
  37.     any of the other CursorCtl routines.  If delaycount = 0, then the default
  38.     delay value of 32 will be used.  Ensure that the value being passed as
  39.     delaycount is 32-bits in size (long)
  40. */
  41.  
  42. extern pascal void Show_Cursor();/*
  43.  
  44.     This function removes the default inverse space cursor from the screen and
  45.     replaces it with the first frame of the animated cursor.  It then outputs a
  46.     backspace so that any subsequent characters will automatically overwrite
  47.     the cursor character.
  48. */
  49.  
  50. extern pascal void RotateCursor(/* counter */);/*
  51. unsigned long   counter;
  52.  
  53.     RotateCursor is called to rotate the "I am active" "spinning wheel" cursor.
  54.     The next cursor ("frame") is used when (counter MOD delaycount) (as
  55.     specified in the InitCursorCtl call) = 0 (counter is some kind of
  56.     incrementing or decrementing index maintained by the caller).  A positive
  57.     counter sequences forward through the cursors (e.g., it rotates the cursor
  58.     "clockwise"), and a negative cursor sequences through the cursors backwards
  59.     (e.g., it rotates the cursor counterclockwise).
  60. */
  61.  
  62. extern pascal void SpinCursor(/* increment */);/*
  63. unsigned short  increment;
  64.  
  65.     SpinCursor is similar in function to RotateCursor, except that instead of
  66.     passing a counter, an increment is passed and added to a counter maintained
  67.     here.  SpinCursor is provided for those users who do not happen to have a
  68.     convenient counter handy but still want to use the spinning cursor.  A
  69.     positive increment sequences forward through the cursors (rotating the
  70.     cursor clockwise), and a negative increment sequences backward through the
  71.     cursors (rotating the cursor counterclockwise).  A zero value for the
  72.     increment resets the counter to zero. Note, it is the increment, and not
  73.     the value of the counter that determines the sequencing direction of the
  74.     cursor (and hence the spin direction of the cursor).
  75. */
  76.  
  77. extern pascal void Hide_Cursor();/*
  78.  
  79.     Hides the current character of the spinning cursor.  Use this routine when
  80.     you wish to revert to the standard inverse space cursor.
  81. */
  82.  
  83. /************************************************************
  84.  
  85.     ErrMgr.h - //GS equivalent of the MPW Error Manager
  86.  
  87. ************************************************************/
  88.  
  89. extern void InitErrMgr(/* toolErrFilename, sysErrFilename, showToolErrNbrs */);
  90. /*  char    *toolErrFilename;
  91.     char    *sysErrFilename;
  92.     boolean showToolErrNbrs;
  93.  
  94.     Initializes the error manager.  If toolErrFilename is not null, this will
  95.     open the resource fork of that file to allow access to tool-specific error
  96.     messages.  If sysErrFilename is not null, this will open the resource fork
  97.     of that file instead of the standard APW error message file. If
  98.     showToolErrNbrs is TRUE, then any call to GetSysErrText will show the
  99.     decimal and hexadecimal error number in parentheses after the text of the
  100.     error message.  If this is false, all that GetSysErrText will provide is
  101.     the text of the message.
  102.     
  103.     To use the error manager, your tool must start up the Resource Manager
  104.     prior to calling InitErrMgr.  This function will NOT do it for you.
  105. */
  106.  
  107. extern void CloseErrMgr();
  108. /*
  109.     This simply closes any resources files opened by InitErrMgr.  It is not
  110.     absolutely required that you call this function prior to exiting your tool,
  111.     but it is available.  If it is not called, the Resource Manager will
  112.     automatically close any files opened.  You must shutdown the Resource
  113.     Manager yourself.
  114. */
  115.  
  116. extern char *GetSysErrText(/* errNbr,errMsg */);
  117. /*  unsigned    errNbr;
  118.     StringPtr   errMsg;
  119.  
  120.     GetSysErrText performs a resource lookup for the supplied errNbr.  It does
  121.     this by calculating which resource number to use from the system resource
  122.     file or the tool-specific error file.
  123.  
  124.     The function places the error message text in the buffer pointed to by
  125.     errMsg, and also returns a pointer to a standard C string representing the
  126.     error message associated with the given error number.  If there is message
  127.     text available for the given error number, the string will have the
  128.     following format:
  129.  
  130.         ### {tool name}: {message text}
  131.     
  132.     If no specific message is available, the string will have the following
  133.     format:
  134.  
  135.         ### {tool name}: Error {decimal error number} ($xxxx)
  136.  
  137.     where $xxxx is the hexadecimal error code.
  138. */
  139.  
  140. /************************************************************
  141.  
  142.     gsString.h - header file for GS/OS string support functions
  143.  
  144. ************************************************************/
  145.  
  146. #ifdef  __GSOS__
  147.  
  148. extern  GSString255 *c2gsstr(/* str, pathGS */);
  149. /*  char        *str;
  150.     GSString255 *pathGS;
  151.     
  152.     This function accepts a null terminated C string and copies it to a
  153.     GS/OS-style string (length word followed by the characters of the string).
  154.     On return, the function returns the pointer to the pathname structure
  155. */
  156.  
  157. extern  char *gs2cstr(/* pathGS, str */);
  158. /*  GSString255 pathGS;
  159.     char        *str;
  160.     
  161.     This function converts a GS/OS-style string (word length followed by the
  162.     characters of the string) to a normal, null terminated C string.  On exit
  163.     it returns a pointer to the string (which is the same as that specified
  164.     on entry).
  165. */
  166.  
  167. extern void colonize(/* fileName */);
  168. /*  char    *fileName;
  169.  
  170.     normalizes a filename string so that it contains only colons as pathname
  171.     separators.  If there are no separators in the filename, the name is left
  172.     unchanged.  If the filename contains no slashes, the filename is left
  173.     unchanged.
  174. */
  175. #endif
  176.  
  177. /************************************************************
  178.  
  179.     pause.h - header file for APW-compatible pause function
  180.  
  181. ************************************************************/
  182.  
  183. extern int pause();
  184. /*
  185.     This function should be called periodically by an APW tool to check for
  186.     a pending keypress and/or command-. (abort signal).  If the command-.
  187.     keypress is pending, the function will return a non-zero value
  188.     (signifying TRUE).  If any other keypress is pending, the function
  189.     will display an hourglass character on the screen and pause until
  190.     another key is pressed.
  191.     
  192.     The value returned is either non-zero (TRUE), indicating that command-.
  193.     has been pressed and the tool should abort, or 0 (false), indicating
  194.     that processing should proceed.
  195. */
  196.  
  197. extern int wait();
  198. /*
  199.     This function operates similarly to the pause() function, except that
  200.     it forces a keypress prior to returning to the caller.  That is, it
  201.     waits in a loop until a keypress occurs.  The values returned are the 
  202.     same as described for the pause() function.
  203. */
  204. #endif
  205.